/* NOTICE
    OpenJaWS - Open Java Weather Station
    
    Copyright (C) 2008 Grant Gardner <grant@lastweekend.com.au>
    
    OpenJaWS is free software: you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program.  If not, see <http://www.gnu.org/licenses/>.
    
NOTICE */

package au.com.lastweekend.openjaws.api;

import java.util.Date;
import java.util.NoSuchElementException;

/**
 * Interface used by plugins to wrap a weather station.
 * 
 * @author grant@lastweekend.com.au
 * @version $Id: codetemplates.xml,v 1.2 2005/01/22 06:53:11 ggardner Exp $
 */
public interface WeatherStation {

    /**
     * Used for stations that don't support historical values
     */
    public static final HistoryIterator NO_HISTORY = new HistoryIterator() {

        public boolean hasNext() {

            return false;
        }

        public void next(Readings readings) throws WeatherStationException {

            throw new NoSuchElementException("No history");
        }
    };

    /**
     * Iterator like interface for visiting the historical readings stored in the WeatherStation
     * 
     * @author grant@lastweekend.com.au
     * @version $Id: codetemplates.xml,v 1.2 2005/01/22 06:53:11 ggardner Exp $
     */
    public interface HistoryIterator {

        public boolean hasNext();

        /**
         * Update the readings with the next historical record, including
         * 
         * {@link Readings#setReadingTime(Date)}
         * 
         * @param readings
         * @throws WeatherStationException
         */
        public void next(Readings readings) throws WeatherStationException;
    }

    /**
     * Update the readings with the current data, including
     * 
     * {@link Readings#setReadingTime(Date)}
     * 
     * @param readings
     * @throws WeatherStationException,
     *             only if something is critically wrong. Individual reading types that are temporarily not available should be
     *             skipped.
     */

    public void fetchReadings(Readings readings) throws WeatherStationException;

    /**
     * 
     * @return Number of seconds before the next reading
     * @throws WeatherStationException
     */
    int getReadDelay() throws WeatherStationException;

    /**
     * 
     * @param fromDate
     *            may be null
     * @return an iterator over historical readings from the supplied date (or all available history if fromDate is null
     * @throws WeatherStationException
     */
    HistoryIterator historyIterator(Date fromDate) throws WeatherStationException;

    /**
     * 
     * If station does not support time then <code>
     * new Date()
     * </code> is an appropriate return value
     * 
     * @return current time from the station.
     * @throws WeatherStationException
     */
    Date getCurrentTime() throws WeatherStationException;

    /**
     * Used to synchronise time with the station
     * 
     * @param date
     * @throws WeatherStationException
     */
    void setCurrentTime(Date date) throws WeatherStationException;

}
